home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / scope / 151-175 / scopedisk157 / hunkfix / hunkfix.doc < prev    next >
Text File  |  1995-03-19  |  13KB  |  305 lines
  1.  
  2.                             HunkFix version 1.4
  3.                          Friday August 31st, 1990
  4.                        Copyright © 1990 Arthur Hagen
  5.  
  6.  
  7.               THIS PROGRAM IS LIMITED DISTRIBUTABLE SHAREWARE
  8.               ===============================================
  9.  
  10.  
  11.   Disclaimer:
  12.   There are NO warranties, either expressed or implied, with respect to the
  13. software,  its quality, performance, or fitness for any particular purpose.
  14. This  software  is  provided "as is" and the entire risk to its quality and
  15. performance  is  with  the  user.  The author of this software shall NOT be
  16. liable   for   errors   contained   in   the  software  or  the  software's
  17. documentation,  or  for  incidental or consequential damages of any kind in
  18. connection with the performance, use or possession of same.
  19.  
  20.   This  program  is "ShareWare", i.e.  if you find this program useful, the
  21. author  would  be  immensely pleased to find a small cheque in his mailbox.
  22. The  suggested  sum  to send is USD 10.00, but the amount could be whatever
  23. sum  you  would  like  to pay.  I cannot develop for free, as I need to buy
  24. coffee, tobacco, harddisks etc.  to wrestle more programs out of the Amiga.
  25.  
  26.   My address (for cheques, praise, bug reports etc.) is:
  27.     Arthur Hagen
  28.     Johan Scharffenbergsvei 99, apt 56
  29.     N-0694  OSLO 6
  30.     Norway, Europe
  31.  
  32.   My bank account:
  33.     ABC Bank, Oslo, Norway    (SWIFT code:  UBNONOKKXXX)
  34.     account no:        /1600.52.26531
  35.     account name:        Arthur Hagen
  36.  
  37.   This  program  is  also "limited distributable".  That means that you may
  38. give it away under certain conditions.  The conditions are as follows:
  39.  
  40.   a) You may NOT charge the receiver any amount for the program itself.
  41.      This  means  that  if  you  are a PD vendor, you may still charge your
  42.      customer for disks, P&P et al, but NOT per program.
  43.   b) You may NOT remove this documentation file.
  44.      This  file,  called  HunkFix.DOC should be included either in the same
  45.      directory, or in the same archive as the main program.
  46.   c) You may NOT change either this file or the program file.
  47.      This includes crunching, translating, changing text, etc.
  48.   d) You  may NOT include it along with any commercial programs, or as part
  49.      of a bargain including such.
  50.  
  51.  
  52.   HUNKS - AN INTRODUCTION
  53.   -----------------------
  54.  
  55.   The following information is useful, but not essential to the use of this
  56. program.   If  you  already  know  about hunks, or don't bother to read all
  57. this, just skip to the next chapter.
  58.  
  59.   The  Amiga  computer  performs  what  is  called "scatter-loading" of all
  60. programs  that  is  run.   This  means that programs most often consists of
  61. several  small  parts that can be loaded anywhere in memory.  These smaller
  62. parts  are  referred  to  as "hunks".  The different hunks in a program are
  63. joined together with some special information to form a loadable file.
  64.  
  65.   Most normal program files consists of these specific hunk types:
  66.  
  67.   Hunk_Header:    Containing info about all other hunks.
  68.   Hunk_Code  :    Containing executable code and/or data.
  69.   Hunk_Data  :    Containing data.
  70.   Hunk_BSS   :    Containing  "uninitialized"  data, i.e. data space that the
  71.         program  needs, but that isn't filled in before the program
  72.         is  run.   This  shortens  the load file, although the same
  73.         amount of memory is required to run the program.
  74.   Hunk_End   :    Marking the end of other hunks.
  75.  
  76.   The  Hunk_Data  can also have BSS space appended to it at the end at load
  77. time.   There  may be zero or more of each hunk type, although (for obvious
  78. reasons)  there  must  be  at least one Hunk_Code present to run a program.
  79. There  should  also  be only one Hunk_Header, and this should be located at
  80. the start of the program file.
  81.  
  82.   Since  these  hunks can be anywhere in memory, AmigaDOS provide means for
  83. the  different  hunks to know where hunks are located in memory.  This info
  84. is  appended  after  each hunk that needs it, and is called a "Reloc-hunk".
  85. Reloc  is an abbreviation for "relocatable", and is called this because the
  86. scatter-loading demands that hunks may be placed anywhere in memory.
  87.  
  88.   There  are six different types of reloc-hunks, of which three can be used
  89. in executable programs:
  90.  
  91.   Hunk_Reloc32:    List of 32-bits modifications to be made to hunks.
  92.   Hunk_Reloc16:    List of 16-bits modifications to be made to hunks.
  93.   Hunk_Reloc8 :    List of  8-bits modifications to be made to hunks.
  94.  
  95. The  number specifies the number of bits the data is referenced by, so that
  96. a  Reloc16 hunk will reference 16-bit data.  As the Amiga has more than 64k
  97. of  memory,  32-bits  references  are  almost always used (16-bits can only
  98. address 64k), so we will most likely never see the Reloc16 and Reloc8 hunks
  99. used.   The Hunk_Reloc32's tells AmigaDOS which hunks it should modify, and
  100. how to do it.
  101.  
  102.   To further increase chaos, there are three other commonly used hunks that
  103. we may encounter in a program file:
  104.  
  105.   Hunk_Name  :   Gives  a  name  to the following hunk.  This is not really
  106.         useful  for  executable  files,  but  is mainly used during
  107.         program development.
  108.   Hunk_Symbol:  Contains information of the names that was used on data and
  109.         program  routines during program development.  This is only
  110.         useful  for  debugging  a program (e.g.  using WACK after a
  111.         Guru).
  112.   Hunk_Debug :  Contains information that can be used by a debugger, but it
  113.         is not very useful unless you have the same debugger as the
  114.         guy who wrote the program.
  115.  
  116.   These  three hunks are not needed to run a program, and may be removed if
  117. you don't want them.
  118.  
  119.   Two special hunk types you may see are:
  120.  
  121.   Hunk_Overlay:    Specifies  that  the  program should load in segments; that
  122.         means  the  whole  file  will not be loaded at once, as one
  123.         would  usually  expect.  Instead some area of memory may be
  124.         overwritten  by  a new part of the program.  This hunk will
  125.         then tell how to accomplish just this.
  126.   Hunk_Break:    Signifies the end of a Hunk_Overlay section.
  127.  
  128.  
  129.   In  addition  to  all these hunks, there are several more hunk types that
  130. may  be  encountered, but as these are of no concern here, they will not be
  131. covered  by  this  manual.   See  the  "AmigaDOS  manual, Bantam Books" for
  132. further information.
  133.  
  134.  
  135.   WHY HUNKFIX?
  136.   ------------
  137.  
  138.   When  developing a program, developers usually use a "linker" to bind all
  139. pieces  of  the  program  together  to  form  an executable file.  As these
  140. linkers  (and those who use them) are far from perfect, surplus information
  141. is  often  stored along with the file.  We, the users, often get files that
  142. are bigger and crave for more memory than what is actually needed.
  143.   The  Lattice development tools often gives us programs that contain empty
  144. hunks,  and the Manx development tools automatically adds 4 unused bytes to
  145. all programs, making the load file 16 bytes larger than necessary.
  146.   HunkFix  will try to remove the parts of load files that are not required
  147. to  run a program, thereby making the program smaller.  It will also try to
  148. rearrange  the program parts so that "think time" during loading is reduced
  149. to a minimum.  As HunkFix will remove all unused parts of a program, it can
  150. also  be  used to "chop" executable files that are received over modem.  No
  151. guarantees are given, though.
  152.  
  153.   Note  that HunkFix is NOT a cruncher or packer, and that HunkFix does NOT
  154. break  any rules made by Commodore (as far as I know).  This means that all
  155. programs  that  have been hunkfixed should function fine under all versions
  156. of the O/S and with no special requirements (i.e.  if the programs would do
  157. so  in  the  first place).  But, as there is NO way to recover the original
  158. file from an hunkfixed one, consider keeping backups of the files.
  159.  
  160.  
  161.   HOW TO USE HUNKFIX:
  162.   -------------------
  163.  
  164.   To  use HunkFix on a program, you have to enter the CLI or Shell environ-
  165. ment  of the Amiga.  Then make sure that the file you want to fix really is
  166. a  loadable  file  that  is  NOT crunched or written in BCPL.  (You may use
  167. VScan by the same author to do this.) Then, if you decide to go on, use the
  168. following command:
  169.  
  170.   1> HunkFix InFile [OutFile]
  171.  
  172.   Here "InFile" is the name of the file you want to fix, and "[OutFile]" is
  173. the  optional  name  of  the file to create.  If you don't enter an OutFile
  174. parameter,  the  original  file  will be overwritten.  NEVER DO THIS if you
  175. don't  have  a  backup  of the file!  Even though HunkFix will work fine on
  176. almost  all  files, you MIGHT find files that won't function properly after
  177. HunkFix  has  been  employed  on  them.   These files are most probably not
  178. written  after  Commodore's specifications, but always keep backups of your
  179. programs no matter what.
  180.  
  181.   If  you decide to stop HunkFix during execution, you may do so by holding
  182. the keys CTRL and C down.  Entering "HunkFix ?" or just "HunkFix" will give
  183. you some short onscreen instructions.
  184.  
  185.   Some examples of files that HunkFix will optimize:
  186.     C:Avail
  187.     C:SetPatch
  188.     most files in LIBS:    (Yes, libraries are loadfiles!)
  189.     most files written with Aztec C or Lattice C
  190.     Itself :-)
  191.  
  192.   Some files that should NOT be HunkFixed:
  193.     C:Install
  194.     All files crunched with TurboImploder(TM) 3.0
  195.     Files made with MultiForth (TM).
  196.  
  197.  
  198.   HOW HUNKFIX WORKS:
  199.   ------------------
  200.  
  201.   If  commands  are  entered correctly, you will see something like this on
  202. screen:
  203.  
  204.     HunkFix version ?.?, ©1990 Arthur Hagen
  205.     Loading file XXXX
  206.     Filesize:        ???? bytes
  207.     Runsize:        ???? bytes
  208.     Program contains      ?? hunks
  209.     Pass 1
  210.     Hunk #0:        ???? bytes
  211.     Hunk_Code
  212.     Hunk_Reloc32
  213.     Hunk_Symbol removed
  214.     Hunk_End
  215.     etc...
  216.     Pass 2
  217.     Hunk #0:
  218.     etc...
  219.     Hunk total:          ?? hunks
  220.     Hunks used:          ?? hunks
  221.     Pass 3
  222.     Hunk #0:             Reloc32 sorted
  223.     Hunk #4:             Reloc32 sorted
  224.     Hunk #4:             Reloc32 squeezed
  225.     etc...
  226.     Pass 4
  227.     Hunk #0:             unchanged
  228.     Hunk #1:             unchanged
  229.     Hunk #2:             merged with hunk #1
  230.     Hunk #3:             removed
  231.     etc...
  232.     Saving file YYYY
  233.     Writing hunk #?
  234.     Old filesize:        ???? bytes
  235.     New filesize:        ???? bytes
  236.     Task completed.
  237.  
  238.  
  239.   HunkFix  will  first load the entire program into memory.  If successful,
  240. it will then start working on the program in four passes.
  241.  
  242.   Pass 1:
  243.   Here  HunkFix  will  scan  all  hunks  of  the  program to ensure that it
  244. recognizes  them.  In addition, Hunk_Name's, Hunk_Symbol's and Hunk_Debug's
  245. will be removed.
  246.  
  247.   Pass 2:
  248.   Here  HunkFix  checks  what hunks are actually needed to run the program,
  249. and  mark  those  that are needed with the hunk number they will receive in
  250. later passes.
  251.  
  252.   Pass 3:
  253.   Here  HunkFix  scans through all Hunk_Reloc32's, and sort their contents.
  254. If  several  Reloc32  sections  can be joined together to save memory, this
  255. will also be done in this pass.
  256.  
  257.   Pass 4:
  258.   HunkFix  will now reshuffle the remaining hunks in the order that HunkFix
  259. established in pass 2.  All empty hunks will be removed, and the first hunk
  260. to be loaded will always be hunk #0.  If hunk #2 is a BSS hunk, and hunk #1
  261. is a data-hunk, the BSS hunk will be merged with the latter.
  262.  
  263.   After  these  four passes, if the program was changed in any way, HunkFix
  264. will  try  to  save  the modified program hunk by hunk.  You will receive a
  265. progress  report  while HunkFix is saving, and should any error occur, this
  266. will also be told.
  267.  
  268.  
  269.   ERRORS:
  270.   -------
  271.  
  272.   You  may find in certain cases that HunkFix aborts with an error message.
  273. These error messages are explained below:
  274.  
  275.   ***ERROR - Empty file!
  276.   You  have  tried  to  use HunkFix on an empty file.  Just delete the file
  277. instead.
  278.  
  279.   ***ERROR - Hunk_Overlay (segmented program), cannot touch it!
  280.   Some  programs  may be written "segmented", i.e.  they will not be loaded
  281. in full at once, but partwise as segments are needed.  These files are more
  282. difficult  to  handle  than others, and the current version of HunkFix will
  283. not do anything to them to avoid damage.
  284.  
  285.   ***ERROR - Unknown hunk: 0x????????
  286.   HunkFix  covers only the most commonly used hunks, but if it finds a hunk
  287. that  it  doesn't  recognize,  it will abort with this error message.  Note
  288. that  some  programs  that are "crunched" to reduce size also will generate
  289. this  error  message.   In  this case it is most often because the crunched
  290. programs  doesn't  follow  the  normal Commodore-approved file format.  The
  291. files  themselves  may run fine now, but maybe not under future versions of
  292. the operating system.
  293.  
  294.   ***ERROR - AmigaDOS error #???
  295.   If  the  AmigaDOS  encounters  an error during program execution, HunkFix
  296. will abort with this error message.  Use 'Fault ???' to determine the exact
  297. cause  of  the  error.  Missspelling a filename or having a write-protected
  298. disk can lead to this error.
  299.  
  300.  
  301.   Greeting to everyone that has bothered to read this far!
  302.  
  303. *Art
  304.  
  305.